
"""
python script to generate index.html
"""


test = False

import sys, os
from skimpyGimpy import skimpyAPI, pngBarChart, pngPieChart
indexFilePath = "../wave/waveIndex.zip"

if not os.path.exists(indexFilePath):
    raise ValueError, "cannot find wave index file "+repr(indexFilePath)

if not test:
    sys.stdout = open("index.html", "w")

print """
<html>
<head>
<title>
Skimpy Gimpy Audio/visual Tools Documentation
</title>
</head>
<body>

"""

def pre(s, filename=None, scale=0.7, speckle=0.1, color="0f116f"):
    """print an inline <pre> captcha"""
    print "[preformatted text]"
    print skimpyAPI.Pre(s, scale, speckle, color).data(filename)

def png(s, filename, scale=2.2, speckle=0.1, color="0f116f", fontpath=None):
    data = skimpyAPI.Png(s, scale=scale, speckle=speckle, color=color, fontpath=fontpath).data(filename)
    print '[PNG image] <br> <img src="%s">' % filename

def wave(s, filename):
    data = skimpyAPI.Wave(s, indexFilePath).data(filename)
    print '<a href="%s">[Wave audio link]</a>' % filename

def all(s, fileprefix):
    print "<center>"
    pre(s, "pre/"+fileprefix+".html")
    print "<br>"
    png(s, "png/"+fileprefix+".png")
    print "<br>"
    wave(s, "wave/"+fileprefix+".wav")
    print "</center>"

all("skimpy gimpy", "skimpy")


print """

<h3>Skimpy Gimpy Audio/visual Tools Documentation</h3>

Skimpy is a tool for generating <b>HTML visual</b>, <b>PNG visual</b>, and <b>WAVE audio</b>
representations for strings which
people can understand but which web
robots and other computer programs will have difficulty understanding.
Skimpy is an example of a <a href="http://en.wikipedia.org/wiki/Captcha">Captcha</a>: 
an acronym for "Completely Automated Public Turing test to tell Computers and Humans Apart".
<p>
The <b>visual</b> HTML and PNG Skimpy generators
translate words or phrases into
strings containing HTML preformatted text
or PNG image files respectively.  The preformatted
text contains "ASCII art" representing the input phrase, which looks like somewhat sloppy handwriting
on a speckled page, when viewed in an HTML browser.
The PNG image contains a "pixelized" version of the word or phrase with added noise.
<p>
It is intended that it is easy for a human to read the word or phrase when rendered
as HTML, but it is difficult for a program to extract the word or phrase automatically.
The program uses a number of techniques to make the output difficult for a computer to
interpret including the
addition of noise.  The preformatted text version is probably more secure than
the PNG version, but it is also harder to read (not surprisingly).
<p>
In order to allow CAPTCHA tests that are usable by people with visual empairment,
Skimpy also provides an <b>audio</b> implementation.
The audio WAVE Skimpy program uses a compiled audio sample file
<code>waveIndex.zip</code>.  The input of the program are words or phrases and the output
are the words or phrases spelled as individual spoken characters in an audio stream.  
<p>
It is intended that a human can understand the audio stream but a computer program
will not be able to analyse the stream and extract the letters. To make
the audio stream more difficult to automatically analyse (without making it unintelligible)
the program randomly overlaps and stretches/shrinks the input samples, among other things.
<p>
The Skimpy tools are far easier to install, use, and embed than other similar technologies.


<h3>The skimpy canvas</h3>
<p>

Also included with the package is a PNG canvas implementation which allows easy programmatic
creation of graphical PNG images.  This interface allows for the the construction of PNG
images from textual fonts or geometric shapes, with transparent or non-transparent backgrounds.
The canvas also can generate Javascript data structures which allow HTML pages to intelligently
respond to mouse events over the image.
<p>
For example below are examples of a bar chart and a pie chart generated by the skimpy canvas.
Mouse over the images to see responses to mouse events (on supported browsers with javascript
enabled).

"""

pngBarChart.test(name="mouseEvents/bars", canvasLocation="canvas.js")
try:
    os.unlink("bars.html")
    os.unlink("pie.html")
except:
    pass
os.rename("mouseEvents/bars.html", "bars.html")
pngPieChart.test(name="mouseEvents/pie", canvasLocation="canvas.js")
os.rename("mouseEvents/pie.html", "pie.html")

print """

<!-- canvas.js contains required utilities -->
<script src="canvas.js"></script>

<!--
Below is a simple example callback function, required by mouseEvents/bars.js.
In real use you will want to customize this code.
-->
<script>
function mouseChart(alertString, x, y, event, image) {
	var span = document.getElementById("chart_span");
	span.innerHTML = "mouseChart called with "+alertString+
            "<br>coords "+x+" "+y+
            " <br>event.type="+event.type+
            " <br>image.id="+image.id+
            " <br>offsets "+window["pageXOffset"]+" "+window["pageYOffset"];
}
</script>

<table width="100%">
<tr>
    <th width="33%">
    <img src="mouseEvents/bars.png" id="chart" height="180" width="180">
    </th>
    <th>
    <span id="chart_span">information about the mouse event over
   either image should appear here.</span>
    </th>
    <th width="33%">
    <img src="mouseEvents/pie.png" id="pieChart" height="180" width="180">
    </th>
</tr>
</table>

<!-- import the automatically generated javascript after "canvas.js" and the image declaration -->
<script src="mouseEvents/bars.js"></script>
<script src="mouseEvents/pie.js"></script>


<a href="canvas.html">
Click here for the canvas documentation.
</a>  Described there you will also find tools for constructing Entity-Relationship diagrams
and "railroad" diagrams using the canvas interface.

<h3>Where do you get it?</h3>

<a href="http://www.sourceforge.net/projects/skimpygimpy/">Please go to the Skimpy Gimpy sourceforge
project page and click on the download link.</a>

<h3>How do you install it?</h3>

Skimpy is a Python package, so you need a recent version of Python to use it.
It has been tested with Python 2.4 and better.  To install the package on your
machine use the <code>setup.py</code> install script in the root directory.
<pre>
prompt> setup.py install
</pre>

<h3>Why is it useful?</h3>

A very simple use of Skimpy is to put an email address that a human can read or listen to on a web
page without making it easy for programs to automatically extract the email address
in order to send spam to the address.  To use Skimpy to create an encoded email address
you could use command lines like this:
<pre>"""

print file("commands.bat").read().strip()

print """</pre>
These commands create an HTML page, a Wave audio file, and a PNG image containing the Skimpy encodings
for <code>myAddress@example.com</code>.  The HTML may
be included in web pages, like this one, and the PNG or Wave may be linked from the
web page as I've done here:
<center>
<code>pre/address.html</code> preformatted text:
"""

print file("pre/address.html").read()

print """
<code>png/address.png</code> PNG image: <br> <img src="png/address.png">
<br>
<a href="wave/address.wav">Click to play <code>wave/address.wav</code> audio encoding.</a>.
</center>
"""

print """

<p>
With any luck human readers of the web page will be able to read the HTML or image
or hear and understand the audio and use the email address
but evil spammer programs will fail to recognize and understand the address.

<p>

Web applications also frequently use Captcha tools like Skimpy to verify that the
agent interacting with a web application is a human and not an automated program or "robot".
To use Skimpy to foil robots include a Skimpy encoded text
(obtained either by using the Python API or by capturing the output from the
Skimpy command line program) near a web form and ask
the "user" to type in the text on the form.  When the user submits the form
verify that the text entered by the user matches the text used to generate the
Skimpy preformatted text.

<p>

A Python CGI script which implements a challenge like this is included in the
distribution: <code>guess.cgi</code>.  The <a href="http://www.xfeedme.com/skimpyGimpy/guess.py/go">
http://www.xfeedme.com/skimpyGimpy/guess.py/go</a> demo page provides a live demo
of this kind of use.  Below is a screen shot of the page:
<center>
<img src="screenshot.PNG">
</center>
Note that this simple minded demo is not "secure" in the sense that it is subject
to "replay attacks" -- if you repeat a URL that succeeded it will succeed again.
For true CAPTCHA security you need to store the CAPTCHA match string in a temporary
opaque session object that the client cannot access in any way.  The hiding of the
CAPTCHA string is beyond the scope of this module and left to the user/programmer's
creativity.
"""


print """
<h3>How do you use it?</h3>

You may generate skimpy text representations either using shell commands or from within
a python program.

<h3>Command line summary</h3>

Below is a summary listing the three command line options for generating HTML preformatted text, PNG
images, or Wave audio files respectively, including optional and required parameters.  In all cases at
least one of <code>--filename</code> or <code>--stdout</code> must be specified.

<center>
<table border>
<tr>
<th>command</th> <th>option</th> <th>explanation</th>
</tr>

<tr>
<td> <code> skimpy.py --pre <font color="green">WORD</font></code> </td>
    <td></td>
        <td> <font color="red">Generate preformatted text HTML for <code><font color="green">WORD</font></code></font> </td>
</tr>

<tr>
<td> </td>
    <td> <code> --filename <font color="green">FILENAME</font></code> </td>
        <td> <font color="red">Direct output to <code><font color="green">FILENAME</font></code>
        (eg, <code>word.html</code>).</td>
</tr>

<tr>
<td> </td>
    <td> <code> --stdout</code> </td>
        <td> <font color="red">Direct output to standard output. </td>
</tr>


<tr>
<td> </td>
    <td> <code> --speckle <font color="green">RATIO</font></code> </td>
        <td> <font color="red">Use speckle noise ratio <code><font color="green">RATIO</font></code>
            (eg 0.1)</td>
</tr>

<tr>
<td> </td>
    <td> <code> --scale <font color="green">NUMBER</font></code> </td>
        <td> <font color="red">Scale font by <code><font color="green">NUMBER</font></code>
             (eg 0.7 or 2.3)</td>
</tr>

<tr>
<td> </td>
    <td> <code> --color <font color="green">HEX6DIGITS</font></code> </td>
        <td> <font color="red">Use color <code><font color="green">HEX6DIGITS</font></code>
        in format <code>RRGGBB</code><br>
           (eg, <code>77ff77</code> for light green or <code>0000aa</code> for dark blue)</td>
</tr>


<tr>
<td> <code> skimpy.py --png <font color="green">WORD</font></code> </td>
    <td></td>
        <td> <font color="red">Generate PNG image for <code><font color="green">WORD</font></code></font> </td>
</tr>


<tr>
<td> </td>
    <td> <code> --filename <font color="green">FILENAME</font></code> </td>
        <td> <font color="red">Direct output to <code><font color="green">FILENAME</font></code>
        (eg, <code>word.png</code>) </td>
</tr>

<tr>
<td> </td>
    <td> <code> --stdout</code> </td>
        <td> <font color="red">Direct output to standard output. </td>
</tr>


<tr>
<td> </td>
    <td> <code> --speckle <font color="green">RATIO</font></code> </td>
        <td> <font color="red">Use speckle noise ratio <code><font color="green">RATIO</font></code>
            (eg 0.1)</td>
</tr>

<tr>
<td> </td>
    <td> <code> --scale <font color="green">NUMBER</font></code> </td>
        <td> <font color="red">Scale font by <code><font color="green">NUMBER</font></code>
             (eg 0.7 or 2.3)</td>
</tr>

<tr>
<td> </td>
    <td> <code> --color <font color="green">HEX6DIGITS</font></code> </td>
        <td> <font color="red">Use color <code><font color="green">HEX6DIGITS</font></code>
        in format <code>RRGGBB</code><br>
           (eg, <code>77ff77</code> for light green or <code>0000aa</code> for dark blue)</td>
</tr>

<tr>
<td> </td>
    <td> <code> --fontpath <font color="green">PATH_TO_BDF_FONT_FILE</font></code> </td>
        <td> <font color="red">Use the BDF font specification located
        in <code><font color="green">PATH_TO_BDF_FONT_FILE</font></code> <br>
           (eg, <code>/usr/local/fonts/timesRoman.bdf</code>)
</tr>


<tr>
<td> <code> skimpy.py --wave <font color="green">WORD</font></code> </td>
    <td></td>
        <td> <font color="red">Generate Wave audio file for <code><font color="green">WORD</font></code></font> </td>
</tr>

<tr>
<td> </td>
    <td> <code> --filename <font color="green">FILENAME</font></code> </td>
        <td> <font color="red">Direct output to <code><font color="green">FILENAME</font></code>
        (eg, <code>word.wav</code>) </td>
</tr>

<tr>
<td> </td>
    <td> <code> --stdout</code> </td>
        <td> <font color="red">Direct output to standard output. </td>
</tr>

<tr>
<td> </td>
    <td> <code> --indexfile <font color="green">PATH_TO_WAVE_INDEX</font></code> </td>
        <td> <b>Required for Wave generation.</b><br>
        <font color="red">Use the zipped wave index located
        at <code><font color="green">PATH_TO_WAVE_INDEX</font></code>, <br>usually the location
        of the wave index file provided in the distribution.<br>
           (eg, <code>../wave/waveIndex.zip</code>)
</tr>

</table>
</center>


<h3>Python API summary</h3>

The Application Program Interface to use from a Python program to generate HTML, PNG or Wave representations
for a word is very similar to the command line interface.  In general, first you specify the parameters for
the word and representation and then you generate the output as shown in the following working example.

"""
print """
<center>
<table border><tr><td>
<pre>%s</pre>
</td></tr>
</table>
</center>""" % file("annotatedAPIexample.py").read().strip()


print """
In the sample code given above the <code>data()</code> methods are called
twice each for illustrative purposes where only one call is needed.

<h3>Example code</h3>

The distribution includes CGI script example uses that test and demonstrate Skimpy.
To use these CGI scripts you will need a web browser such as Apache with cgi-scripts
enabled.  You will also need to edit the files to change filesystem paths in their
content.
<p>
<code><a href="http://www.xfeedme.com/skimpyGimpy/guess.py/go">guess.cgi</a></code> 
implements a simple challenge/response which tests whether
the web client agent can understand a word encoded by Skimpy.
<p>
<code><a href="http://www.xfeedme.com/skimpyGimpy/skimpytest.py/go">skimpytest.cgi</a></code> 
provides a web interface for generating Skimpy representations
for strings where the user can type in a string and see or hear a Skimpy representation for the string.

<h3>Advanced usage</h3>

Internally Skimpy encodes visual characters using sequences of spline curve control points.
The 
<a href="http://www.xfeedme.com/skimpyGimpy/interpolate.py/go"><code>interpolate.cgi</code></a>
CGI script aides in construction of these control point
representations.  It is possible to modify the default choice of character mappings
or to use several alternative character mappings.  Since it's hard to explain, suffice
it to say that if you want to change the character glyphs and
can't figure out how to do it for yourself send questions via email using the address below.
<p>
Audio character pronunciations are stored as piecewise linear approximations
of input samples.  It is possible to build and use alternative indices of alternative
sample sets, but this document does not explain that procedure either at this time, sorry.

<h3>Author and copyright</h3>

This software and documentation was written by Aaron Watters, 2006, and is distributed
under the BSD open source license.  If you have questions or comments please contact
me using the email address below.
"""


all("arw1961@yahoo.com", "myemail")

print """

</body>
</html>
"""
